---
title: 图像生成开发环境配置
description: 配置本地环境以开发文本生图和图像处理功能
---

# 图像生成开发环境配置

本指南帮助开发者配置本地环境，用于开发图像生成功能（文生图、图生图）等和文件存储能力。

## 前置条件

- 已安装并运行 Docker
- 已安装 Node.js 和 pnpm
- PostgreSQL 客户端工具（可选，用于调试）

<Callout type="warning">
  **安全提醒**：此配置仅适用于本地开发。使用的默认凭据和开放权限不适合生产环境。
</Callout>

## 快速配置

运行提供的脚本来自动配置所有必需的服务：

```bash
# 配置 PostgreSQL 和 MinIO 用于图像存储
./scripts/setup-image-generation-dev.sh

# 启动开发服务器
pnpm dev:desktop
```

此脚本将执行：

1. 启动 PostgreSQL（本地开发无需身份验证）
2. 运行数据库迁移以初始化模式
3. 启动 MinIO（S3 兼容存储）
4. 创建并配置存储桶
5. 在 `.env.desktop` 中添加必要的 S3 环境变量

## 架构概览

图像生成功能需要：

- **PostgreSQL**：存储生成图像的元数据
- **MinIO/S3**：存储实际的图像文件
- **服务器模式**：文件处理所需（`NEXT_PUBLIC_SERVICE_MODE=server`）

## 环境配置

以下环境变量会被配置脚本自动设置：

```bash
# S3 存储配置（本地开发使用 MinIO）
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=lobe-chat
S3_REGION=us-east-1
S3_PUBLIC_DOMAIN=http://localhost:9000/lobe-chat
S3_ENABLE_PATH_STYLE=1  # MinIO 必需
```

## 开发工作流

### 1. 图像生成 API

在开发图像生成功能时，生成的图像将：

1. 由 AI 模型创建
2. 通过预签名 URL 上传到 S3/MinIO
3. 元数据存储在 PostgreSQL 中
4. 通过公共 S3 URL 提供服务

### 2. 文件存储结构

```
lobe-chat/           # S3 存储桶
├── generated/       # 生成的图像
│   └── {userId}/
│       └── {sessionId}/
│           └── {imageId}.png
└── uploads/         # 用户上传的图像处理文件
    └── {userId}/
        └── {fileId}.{ext}
```

### 3. 测试您的实现

配置环境后，您可以测试：

```typescript
// 示例：上传生成的图像
const uploadUrl = await trpc.upload.createPresignedUrl.mutate({
  filename: 'generated-image.png',
  contentType: 'image/png',
});

// 上传到 S3
await fetch(uploadUrl, {
  method: 'PUT',
  body: imageBlob,
  headers: { 'Content-Type': 'image/png' },
});
```

## 手动配置

如果您希望手动配置服务：

### PostgreSQL

```bash
docker run -d --name lobe-postgres \
  -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  -e POSTGRES_DB=postgres \
  postgres:15
```

### MinIO

```bash
# 启动 MinIO
docker run -d --name lobe-minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  quay.io/minio/minio:RELEASE.2025-04-22T22-12-26Z \
  server /data --console-address ":9001"

# 创建存储桶
docker run --rm \
  --link lobe-minio:minio \
  --entrypoint bash \
  quay.io/minio/mc:RELEASE.2025-04-18T16-45-00Z \
  -c "
    mc config host add minio http://minio:9000 minioadmin minioadmin &&
    mc mb minio/lobe-chat &&
    mc anonymous set public minio/lobe-chat
  "
```

## 服务地址

- **PostgreSQL**：`postgres://postgres@localhost:5432/postgres`
- **MinIO API**：`http://localhost:9000`
- **MinIO 控制台**：`http://localhost:9001` (minioadmin/minioadmin)
- **应用程序**：`http://localhost:3015`

## 故障排除

### 端口冲突

如果端口已被占用：

```bash
# 检查端口使用情况
lsof -i :5432  # PostgreSQL
lsof -i :9000  # MinIO API
lsof -i :9001  # MinIO 控制台
```

### 重置环境

要完全重置开发环境：

```bash
# 停止并删除容器
docker stop lobe-postgres lobe-minio
docker rm lobe-postgres lobe-minio

# 重新运行配置
./scripts/setup-image-generation-dev.sh
```

### 数据库迁移

配置脚本会自动运行迁移。如需手动运行：

```bash
pnpm db:migrate
```

注意：在使用 `pnpm dev:desktop` 的开发模式下，迁移也会在启动时自动运行。

## 相关文档

- [服务器数据库配置](/docs/self-hosting/server-database)
- [S3 存储配置](/docs/self-hosting/advanced/s3)
- [环境变量](/docs/self-hosting/environment-variables)
